Usage Guidelines
This section provides general information and guidelines for API developers.
General Conventions
Makes sure you refer to these general usage guidelines when using the Public API resources.
- URL domain name should be provided during actual integration.
- All element names (attributes, parameters, functions) are camel case.
- All URLs are kebab-case.
- All enumerations (ENUMs), abbreviations and error codes are UPPERCASE, except those that appear in URLs.
- When an API call fails on protocol level (HTTP), response section becomes invalid.
- All {type} and {value} pairs, define the search criteria. Valid {type} ENUMs are: ‘imsi’, ‘iccid’, ‘msisdn’, ‘imei’.
- Every place where {id} is indicated, UUID of the entity object should be used. For example: ‘/api/v2/customer/{id}/offer/{id}/usage’; the first {id} refers to the customer UUID, while the second {id} refers to the Offer.
- Relevant elements are validated using regular expressions. For example, email address. Proper message will be sent when such validation is being breached.
- Whenever a date type element exists without format, the following date format applies: DDMMYYYY.
- Whenever a date/time type element exists without format, the following date/time format applies: YYYY-MM-DD HH:MI:SS
Request Capabilities
As part of the request URL, public APIs support additional request capabilities such as paging, sorting and searching. All these input parameters can be sent as part of the URL of “GET” method type APIs. The following table describes the additional request capabilities:
| Keyword | Type | Default | Description |
|---|---|---|---|
| size | Numeric | 50 | Requested page size i.e., how many records are requested per a single page. |
| Page | Numeric | 0 | Requested page out of the available pages. First page number is always ‘0’. |
| Sort | String | id,asc | Requested sorting by field and whether to sort ascending {asc} or descending {desc}. |
Response Structure
Response structure is divided into two separate structures:
- Synchronous API calls
- ;Asynchronous API calls
- Synchronous Structure
The Synchronous API call structure contains the following elements:
- HTTP code 200 OK and response body for successful operations.
- ‘errorCode’ and ‘errorMessage’ with the error relevant information for failures.
- Optional object supporting paging.
NOTE: The Get Request Status API is treated as pure synchronous API.
Asynchronous Structure
Asynchronous API call structure contains the following elements:
ACK: HTTP code 202 Accepted.
Response body containing the request instance ID used by external systems to query an asynchronous call (operation) status, whether in progress, successful or failed.
NAK: HTTP error code.
errorCode contains the code given by Public APIs microservice for the failure. For example, GLOBAL_1001.
When NAK is returned, the error code category can be GLOBAL_** only.The errorMessage contains the error description for the errorCode. For example
“Service unavailable. Please try again”.
API Call Processing Overlap
When submitting an API call, the following error message (error code “GLOBAL_1014) may sometimes appear:
The system is currently processing another action, please wait until the previous action is completed and then try again.
In this circumstance, the system is processing another action (of the same API call) and so cannot perform the requested API call. When this happens, the Requester, or the Front End application that operates the requests, should wait until the previous action is completed (regardless of Success or Failure) and then submit the request again.